tarazed.5
This manual page contains the configuration file for tarazed. See also tarazed(1).
TARAZED(5) File Formats Manual TARAZED(5)
NAME
tarazed —— documentation of tarazed(1) configuration file
DESCRIPTION
tarazed In the tarazed configuration files, each line contains one direc‐
tive. A directive may enter a special context, using a brace block. Note
that due to limitations of the used library, the opening brace must unfor‐
tunately be placed on the same line as the context name. A directive may
contain multiple strings. If one of these strings contains whitespace, it
must be quoted. Comments start with an octothorpe ‘#’ .
# Comment.
context {
directive argument-1 "argument 2"
}
Each context has its own set of valid directives. A context or directive is
called “toplevel” if it is valid in the default context of the configura‐
tion file.
BINDS
The binds context is used to define key- and pointerbinds. Each directive
creates one bind.
A bind directive constist of one or more key descriptors, a command and ar‐
guments to that command. Command names always start with an exclamation
mark.
binds {
key-descriptor-1 key-descriptor-2 !command arg-1 arg-2
}
Key descriptors are zero, one or more modifiers and exactly one key name,
all separated by hyphens. Multiple key descriptors after one another de‐
scribe a “key chord,” meaning the keys must be pressed in sequence.
The following abbreviations for modifier key names can be used in key de‐
scriptors.
Abbreviation Common Name(s)
S Super, Mod4, Windows Key
H Hyper
M Meta, Alt
s Shift
C Control
As an example S-x S-M-m means first pressing the Super key and the ‘x’ key
simultaneously, then releasing both, then pressing the Super key, the Alt
key, and the ‘m’ key simultaneously. Note that modifier keys must not nec‐
essarily be released in a sequence if two or more consecutive key descrip‐
tors include it.
The following commands are supported.
!spawn <shell command>
Spawn a shell command. Note that the shell command must not
be quoted. All tokens following the !spawn command are assem‐
bled into a command string automatically, for convenience.
!focus-by-char <character> [integer from 0 to 100 (inclusive) | “never”]
Try to focus a window using the following heuristic:
1. Search all windows on the same output as the cur‐
rently focused window for an app-id which starts
with the provided character, in decending z order.
See “IDIOSYNCRACIES” in tarazed(1) to understand
when a window is considered to be on an output.
For app-ids following the reverse domain name
specification, only the last token is regarded;
‘org.gnome.evince’ will match ‘e.’ Matching is
case insensitive.
2. Same as above, but on all outputs.
3. Check whether the currently focused windows app-id
starts with the character.
4. Search all windows on the same output as the cur‐
rently focused window for a title which starts
with the character, in decending z order
5. Same as above, but on all outputs.
6. Check whether the currently focused windows title
starts with the character.
The window is moved to the top in z order if it is occluded
by other windows by at least the threshold amount. The
threshold can be set via the optional second argument, which
is interpreted as a percentage and defaults to 25. If set to
“never,” the window will not be raised.
!focus-by-app-id <string> [integer from 0 to 100 (inclusive) | “never”]
Try to focus a window with an app-id matching the given
string, preferring to stay on the same output as the cur‐
rently focused window. See “IDIOSYNCRACIES” in tarazed(1) to
understand when a window is considered to be on an output.
The window is moved to the top in z order if it is occluded
by other windows by at least the threshold amount. The
threshold can be set via the optional second argument, which
is interpreted as a percentage and defaults to 25. If set to
“never,” the window will not be raised.
If no window was found, but the currently focused window
matches the app-id, then it is raised as described above.
!toggle-maximized
Toggle maximization state of currently focused window.
!toggle-fullscreen
Toggle fullscreen state of currently focused window.
!raise Move currently focused window to the top in z order.
!lower Move currently focused window to the bottom in z order.
!close Close currently focused window.
!exit-session
End the river(1) session.
!dismiss-window
Move currently focused window to the bottom in z order and
focus the highest window in z order on the same output. Con‐
ceptionally similar to bury-buffer in emacs(1).
!dismiss-window-and-related
Move currently focused window and all windows that share its
app-id to the bottom in z order and focus the highest window
in z order on the same output.
!dismiss-related-windows
Move all window matching the app if of the currently focused
window to the bottom in z order, except for the currently fo‐
cused window.
THEME
The theme context is used to configure how tarazed looks.
All configurable sizes are in unscaled pixels. Colours are RGB or RGBA, us‐
ing common hexadecimal notation with two digits per channel and the ‘0x’
prefix. Gradients are contexts in which individual gradient stops can be
defined; each directive in a gradient context contains two values, a deci‐
mal number between 0.0 and 1.0 (inclusive), which is the relative position
of the stop along the gradient, and a colour.
example-gradient {
0.00 0x202020
0.40 0x78B72E
1.0 0x202020
}
The following directives are supported in the theme context.
window-border-size <positive integer>
The width of the window border, without shadows
window-shadow-size <positive integer>
The width of the windows shadows.
block-size <positive integer>
Size of block-style widgets, like the clock.
block-border-size <positive integer>
Size of the border of block-style widgets.
lcd-block-border-size <positive integer>
Size of the border of lcd-block-style widgets, like the
clock.
lcd-block-padding <positive integer>
Padding between outer edges and content for lcd-block-style
widgets, like the clock.
lcd-segment-size <positive integer>
Width of the segments in the seven segment digits for lcd-
block-style widgets, like the clock.
block-background-colour <colour>
Background colour for block-style widgets.
lcd-block-background-colour <colour>
Background colour for lcd-block-style widgets, like the
clock.
lcd-segment-on-colour <colour>
Colour of active segments in seven segment digits for lcd-
block-style widgets, like the clock.
lcd-segment-off-colour <colour>
Colour of inactive segments in seven segment digits for lcd-
block-style widgets, like the clock.
background-colour <colour>
Background colour for all outputs.
window-shadow-gradient { ...
Gradient of the window shadow in all four directions, going
away from the window.
window-border-focused-gradient { ...
Gradient of the border for focused windows. It is applied so
that the window borders form a bezel.
window-border-unfocused-gradient { ...
Gradient of the border for unfocused windows. It is applied
so that the window borders form a bezel.
lcd-block-border-gradient { ...
Gradient of the border of lcd-block-style widgets. It is ap‐
plied so that the borders form a bezel.
block-border-top-gradient { ...
Gradient of the top and left borders of block-style widgets.
block-border-bottom-gradient { ...
Gradient of the bottom and right borders of block-style wid‐
gets.
SPECIAL
The set-env context allows to set environment variables. Each directive in
this context consist of exactly two tokens, the name of the variable to be
set and its string value.
set-env {
XDG_CURRENT_DESKTOP tarazed
MY_FANCY_ENV_VAR "my fancy string"
}
The match context allows to guard configuration behind string comparison
against either built-in variables or environment variables. It expects a
single argument, the name of the variable to be matched. The name of envi‐
ronment variables must start with ‘$’ . Currently only one built-in vari‐
able is supported, “hostname” .
Inside the match context, each directive contains one or ore strings, the
match options. Each directive also opens a new context, which is entered
when one of the match options equals the value of the variable that is com‐
pared against. Inside this context, all toplevel directives and contexts,
excpect match itself, can be used.
match hostname {
eurydike {
theme {
window-shadow-size 10
}
}
artemis m5 {
theme {
window-shadow-size 5
}
}
# For advanced configuration, you can use the
# same match options multiple times in a single
# match context.
euridyke artemis {
theme {
window-border-size 0
}
binds {
# ....
}
}
}
# You could use env var matching to choose between
# multiple themes.
match $THEME {
solarized {
theme {
# ....
}
}
gruvbox {
theme {
# ....
}
}
base16-green {
theme {
# ....
}
}
}
FILES
/etc/tarazed/config
The global configuration file.
$XDG_CONFIG_HOME/tarazed/config or $HOME/.config/tarazed/config
The user configuration file
SEE ALSO
tarazed(1), river(1)
AUTHORS
Leon Henrik Plickat <leonhenrik.plickat@mpinat.mpg.de>
ETHICS
Neither tarazed itself nor this manual page are infected by the LLM rot.
This project is entirely free of generative AI and similar machine learning
abominations.
??? 2026-03-11 TARAZED(5)